/*
 * Copyright (c) 2005, 2011, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */

package javax.xml.ws.spi;

import java.net.URL;
import java.util.List;
import java.util.Iterator;
import java.util.Map;
import java.lang.reflect.Method;
import javax.xml.namespace.QName;
import javax.xml.ws.*;
import javax.xml.ws.wsaddressing.W3CEndpointReference;

import org.w3c.dom.Element;

/**
 * Service provider for <code>ServiceDelegate</code> and
 * <code>Endpoint</code> objects.
 * <p>
 *
 * @since JAX-WS 2.0
 */
public abstract class Provider {

  /**
   * A constant representing the property used to lookup the
   * name of a <code>Provider</code> implementation
   * class.
   */
  static public final String JAXWSPROVIDER_PROPERTY
      = "javax.xml.ws.spi.Provider";

  /**
   * A constant representing the name of the default
   * <code>Provider</code> implementation class.
   **/
  // Using two strings so that package renaming doesn't change it
  static final String DEFAULT_JAXWSPROVIDER
      = "com.sun" + ".xml.internal.ws.spi.ProviderImpl";

  /**
   * Take advantage of Java SE 6's java.util.ServiceLoader API.
   * Using reflection so that there is no compile-time dependency on SE 6.
   */
  static private final Method loadMethod;
  static private final Method iteratorMethod;

  static {
    Method tLoadMethod = null;
    Method tIteratorMethod = null;
    try {
      Class<?> clazz = Class.forName("java.util.ServiceLoader");
      tLoadMethod = clazz.getMethod("load", Class.class);
      tIteratorMethod = clazz.getMethod("iterator");
    } catch (ClassNotFoundException ce) {
      // Running on Java SE 5
    } catch (NoSuchMethodException ne) {
      // Shouldn't happen
    }
    loadMethod = tLoadMethod;
    iteratorMethod = tIteratorMethod;
  }


  /**
   * Creates a new instance of Provider
   */
  protected Provider() {
  }

  /**
   * Creates a new provider object.
   * <p>
   * The algorithm used to locate the provider subclass to use consists
   * of the following steps:
   * <p>
   * <ul>
   * <li>
   * If a resource with the name of
   * <code>META-INF/services/javax.xml.ws.spi.Provider</code>
   * exists, then its first line, if present, is used as the UTF-8 encoded
   * name of the implementation class.
   * </li>
   * <li>
   * If the $java.home/lib/jaxws.properties file exists and it is readable by
   * the <code>java.util.Properties.load(InputStream)</code> method and it contains
   * an entry whose key is <code>javax.xml.ws.spi.Provider</code>, then the value of
   * that entry is used as the name of the implementation class.
   * </li>
   * <li>
   * If a system property with the name <code>javax.xml.ws.spi.Provider</code>
   * is defined, then its value is used as the name of the implementation class.
   * </li>
   * <li>
   * Finally, a default implementation class name is used.
   * </li>
   * </ul>
   */
  public static Provider provider() {
    try {
      Object provider = getProviderUsingServiceLoader();
      if (provider == null) {
        provider = FactoryFinder.find(JAXWSPROVIDER_PROPERTY, DEFAULT_JAXWSPROVIDER);
      }
      if (!(provider instanceof Provider)) {
        Class pClass = Provider.class;
        String classnameAsResource = pClass.getName().replace('.', '/') + ".class";
        ClassLoader loader = pClass.getClassLoader();
        if (loader == null) {
          loader = ClassLoader.getSystemClassLoader();
        }
        URL targetTypeURL = loader.getResource(classnameAsResource);
        throw new LinkageError("ClassCastException: attempting to cast" +
            provider.getClass().getClassLoader().getResource(classnameAsResource) +
            "to" + targetTypeURL.toString());
      }
      return (Provider) provider;
    } catch (WebServiceException ex) {
      throw ex;
    } catch (Exception ex) {
      throw new WebServiceException("Unable to createEndpointReference Provider", ex);
    }
  }


  private static Provider getProviderUsingServiceLoader() {
    if (loadMethod != null) {
      Object loader;
      try {
        loader = loadMethod.invoke(null, Provider.class);
      } catch (Exception e) {
        throw new WebServiceException("Cannot invoke java.util.ServiceLoader#load()", e);
      }

      Iterator<Provider> it;
      try {
        it = (Iterator<Provider>) iteratorMethod.invoke(loader);
      } catch (Exception e) {
        throw new WebServiceException("Cannot invoke java.util.ServiceLoader#iterator()", e);
      }
      return it.hasNext() ? it.next() : null;
    }
    return null;
  }

  /**
   * Creates a service delegate object.
   * <p>
   *
   * @param wsdlDocumentLocation A URL pointing to the WSDL document for the service, or
   * <code>null</code> if there isn't one.
   * @param serviceName The qualified name of the service.
   * @param serviceClass The service class, which MUST be either <code>javax.xml.ws.Service</code>
   * or a subclass thereof.
   * @return The newly created service delegate.
   */
  public abstract ServiceDelegate createServiceDelegate(
      java.net.URL wsdlDocumentLocation,
      QName serviceName, Class<? extends Service> serviceClass);

  /**
   * Creates a service delegate object.
   * <p>
   *
   * @param wsdlDocumentLocation A URL pointing to the WSDL document for the service, or
   * <code>null</code> if there isn't one.
   * @param serviceName The qualified name of the service.
   * @param serviceClass The service class, which MUST be either <code>javax.xml.ws.Service</code>
   * or a subclass thereof.
   * @param features Web Service features that must be configured on the service. If the provider
   * doesn't understand a feature, it must throw a WebServiceException.
   * @return The newly created service delegate.
   * @since JAX-WS 2.2
   */
  public ServiceDelegate createServiceDelegate(
      java.net.URL wsdlDocumentLocation,
      QName serviceName, Class<? extends Service> serviceClass, WebServiceFeature... features) {
    throw new UnsupportedOperationException(
        "JAX-WS 2.2 implementation must override this default behaviour.");
  }


  /**
   * Creates an endpoint object with the provided binding and implementation
   * object.
   *
   * @param bindingId A URI specifying the desired binding (e.g. SOAP/HTTP)
   * @param implementor A service implementation object to which incoming requests will be
   * dispatched. The corresponding class MUST be annotated with all the necessary Web service
   * annotations.
   * @return The newly created endpoint.
   */
  public abstract Endpoint createEndpoint(String bindingId,
      Object implementor);


  /**
   * Creates and publishes an endpoint object with the specified
   * address and implementation object.
   *
   * @param address A URI specifying the address and transport/protocol to use. A http: URI MUST
   * result in the SOAP 1.1/HTTP binding being used. Implementations may support other URI schemes.
   * @param implementor A service implementation object to which incoming requests will be
   * dispatched. The corresponding class MUST be annotated with all the necessary Web service
   * annotations.
   * @return The newly created endpoint.
   */
  public abstract Endpoint createAndPublishEndpoint(String address,
      Object implementor);

  /**
   * read an EndpointReference from the infoset contained in
   * <code>eprInfoset</code>.
   *
   * @param eprInfoset infoset for EndpointReference
   * @return the <code>EndpointReference</code> unmarshalled from <code>eprInfoset</code>.  This
   * method never returns <code>null</code>.
   * @throws WebServiceException If there is an error creating the <code>EndpointReference</code>
   * from the specified <code>eprInfoset</code>.
   * @throws NullPointerException If the <code>null</code> <code>eprInfoset</code> value is given.
   * @since JAX-WS 2.1
   **/
  public abstract EndpointReference readEndpointReference(javax.xml.transform.Source eprInfoset);


  /**
   * The getPort method returns a proxy.  If there
   * are any reference parameters in the
   * <code>endpointReference</code>, then those reference
   * parameters MUST appear as SOAP headers, indicating them to be
   * reference parameters, on all messages sent to the endpoint.
   * The parameter  <code>serviceEndpointInterface</code> specifies
   * the service endpoint interface that is supported by the
   * returned proxy.
   * The parameter <code>endpointReference</code> specifies the
   * endpoint that will be invoked by the returned proxy.
   * In the implementation of this method, the JAX-WS
   * runtime system takes the responsibility of selecting a protocol
   * binding (and a port) and configuring the proxy accordingly from
   * the WSDL metadata of the
   * <code>serviceEndpointInterface</code> and the <code>EndpointReference</code>.
   * For this method
   * to successfully return a proxy, WSDL metadata MUST be available and the
   * <code>endpointReference</code> MUST contain an implementation understood
   * <code>serviceName</code> metadata.
   *
   * @param endpointReference the EndpointReference that will be invoked by the returned proxy.
   * @param serviceEndpointInterface Service endpoint interface
   * @param features A list of WebServiceFeatures to configure on the proxy.  Supported features not
   * in the <code>features </code> parameter will have their default values.
   * @return Object Proxy instance that supports the specified service endpoint interface
   * @throws WebServiceException <UL> <LI>If there is an error during creation of the proxy <LI>If
   * there is any missing WSDL metadata as required by this method} <LI>If this
   * <code>endpointReference</code> is illegal <LI>If an illegal <code>serviceEndpointInterface</code>
   * is specified <LI>If a feature is enabled that is not compatible with this port or is
   * unsupported. </UL>
   * @see WebServiceFeature
   * @since JAX-WS 2.1
   **/
  public abstract <T> T getPort(EndpointReference endpointReference,
      Class<T> serviceEndpointInterface,
      WebServiceFeature... features);

  /**
   * Factory method to create a <code>W3CEndpointReference</code>.
   *
   * <p>
   * This method can be used to create a <code>W3CEndpointReference</code>
   * for any endpoint by specifying the <code>address</code> property along
   * with any other desired properties.  This method
   * can also be used to create a <code>W3CEndpointReference</code> for
   * an endpoint that is published by the same Java EE application.
   * To do so the <code>address</code> property can be provided or this
   * method can automatically determine the <code>address</code> of
   * an endpoint that is published by the same Java EE application and is
   * identified by the <code>serviceName</code> and
   * <code>portName</code> propeties.  If the <code>address</code> is
   * <code>null</code> and the <code>serviceName</code> and
   * <code>portName</code> do not identify an endpoint published by the
   * same Java EE application, a
   * <code>javax.lang.IllegalStateException</code> MUST be thrown.
   *
   * @param address Specifies the address of the target endpoint
   * @param serviceName Qualified name of the service in the WSDL.
   * @param portName Qualified name of the endpoint in the WSDL.
   * @param metadata A list of elements that should be added to the <code>W3CEndpointReference</code>
   * instances <code>wsa:metadata</code> element.
   * @param wsdlDocumentLocation URL for the WSDL document location for the service.
   * @param referenceParameters Reference parameters to be associated with the returned
   * <code>EndpointReference</code> instance.
   * @return the <code>W3CEndpointReference</code> created from <code>serviceName</code>,
   * <code>portName</code>, <code>metadata</code>, <code>wsdlDocumentLocation</code> and
   * <code>referenceParameters</code>. This method never returns <code>null</code>.
   * @throws java.lang.IllegalStateException <ul> <li>If the <code>address</code>,
   * <code>serviceName</code> and <code>portName</code> are all <code>null</code>. <li>If the
   * <code>serviceName</code> service is <code>null</code> and the <code>portName</code> is NOT
   * <code>null</code>. <li>If the <code>address</code> property is <code>null</code> and the
   * <code>serviceName</code> and <code>portName</code> do not specify a valid endpoint published by
   * the same Java EE application. <li>If the <code>serviceName</code>is NOT <code>null</code> and
   * is not present in the specified WSDL. <li>If the <code>portName</code> port is not
   * <code>null</code> and it is not present in <code>serviceName</code> service in the WSDL. <li>If
   * the <code>wsdlDocumentLocation</code> is NOT <code>null</code> and does not represent a valid
   * WSDL. </ul>
   * @throws WebServiceException If an error occurs while creating the
   * <code>W3CEndpointReference</code>.
   * @since JAX-WS 2.1
   */
  public abstract W3CEndpointReference createW3CEndpointReference(String address, QName serviceName,
      QName portName,
      List<Element> metadata, String wsdlDocumentLocation, List<Element> referenceParameters);


  /**
   * Factory method to create a <code>W3CEndpointReference</code>.
   * Using this method, a <code>W3CEndpointReference</code> instance
   * can be created with extension elements, and attributes.
   * <code>Provider</code> implementations must override the default
   * implementation.
   *
   * <p>
   * This method can be used to create a <code>W3CEndpointReference</code>
   * for any endpoint by specifying the <code>address</code> property along
   * with any other desired properties.  This method
   * can also be used to create a <code>W3CEndpointReference</code> for
   * an endpoint that is published by the same Java EE application.
   * To do so the <code>address</code> property can be provided or this
   * method can automatically determine the <code>address</code> of
   * an endpoint that is published by the same Java EE application and is
   * identified by the <code>serviceName</code> and
   * <code>portName</code> propeties.  If the <code>address</code> is
   * <code>null</code> and the <code>serviceName</code> and
   * <code>portName</code> do not identify an endpoint published by the
   * same Java EE application, a
   * <code>javax.lang.IllegalStateException</code> MUST be thrown.
   *
   * @param address Specifies the address of the target endpoint
   * @param interfaceName the <code>wsam:InterfaceName</code> element in the
   * <code>wsa:Metadata</code> element.
   * @param serviceName Qualified name of the service in the WSDL.
   * @param portName Qualified name of the endpoint in the WSDL.
   * @param metadata A list of elements that should be added to the <code>W3CEndpointReference</code>
   * instances <code>wsa:metadata</code> element.
   * @param wsdlDocumentLocation URL for the WSDL document location for the service.
   * @param referenceParameters Reference parameters to be associated with the returned
   * <code>EndpointReference</code> instance.
   * @param elements extension elements to be associated with the returned
   * <code>EndpointReference</code> instance.
   * @param attributes extension attributes to be associated with the returned
   * <code>EndpointReference</code> instance.
   * @return the <code>W3CEndpointReference</code> created from <code>serviceName</code>,
   * <code>portName</code>, <code>metadata</code>, <code>wsdlDocumentLocation</code> and
   * <code>referenceParameters</code>. This method never returns <code>null</code>.
   * @throws java.lang.IllegalStateException <ul> <li>If the <code>address</code>,
   * <code>serviceName</code> and <code>portName</code> are all <code>null</code>. <li>If the
   * <code>serviceName</code> service is <code>null</code> and the <code>portName</code> is NOT
   * <code>null</code>. <li>If the <code>address</code> property is <code>null</code> and the
   * <code>serviceName</code> and <code>portName</code> do not specify a valid endpoint published by
   * the same Java EE application. <li>If the <code>serviceName</code>is NOT <code>null</code> and
   * is not present in the specified WSDL. <li>If the <code>portName</code> port is not
   * <code>null</code> and it is not present in <code>serviceName</code> service in the WSDL. <li>If
   * the <code>wsdlDocumentLocation</code> is NOT <code>null</code> and does not represent a valid
   * WSDL. <li>If the <code>wsdlDocumentLocation</code> is NOT <code>null</code> but
   * wsdli:wsdlLocation's namespace name cannot be got from the available metadata. </ul>
   * @throws WebServiceException If an error occurs while creating the
   * <code>W3CEndpointReference</code>.
   * @since JAX-WS 2.2
   */
  public W3CEndpointReference createW3CEndpointReference(String address,
      QName interfaceName, QName serviceName, QName portName,
      List<Element> metadata, String wsdlDocumentLocation, List<Element> referenceParameters,
      List<Element> elements, Map<QName, String> attributes) {
    throw new UnsupportedOperationException(
        "JAX-WS 2.2 implementation must override this default behaviour.");
  }

  /**
   * Creates and publishes an endpoint object with the specified
   * address, implementation object and web service features.
   * <code>Provider</code> implementations must override the
   * default implementation.
   *
   * @param address A URI specifying the address and transport/protocol to use. A http: URI MUST
   * result in the SOAP 1.1/HTTP binding being used. Implementations may support other URI schemes.
   * @param implementor A service implementation object to which incoming requests will be
   * dispatched. The corresponding class MUST be annotated with all the necessary Web service
   * annotations.
   * @param features A list of WebServiceFeatures to configure on the endpoint.  Supported features
   * not in the <code>features </code> parameter will have their default values.
   * @return The newly created endpoint.
   * @since JAX-WS 2.2
   */
  public Endpoint createAndPublishEndpoint(String address,
      Object implementor, WebServiceFeature... features) {
    throw new UnsupportedOperationException(
        "JAX-WS 2.2 implementation must override this default behaviour.");
  }

  /**
   * Creates an endpoint object with the provided binding, implementation
   * object and web service features. <code>Provider</code> implementations
   * must override the default implementation.
   *
   * @param bindingId A URI specifying the desired binding (e.g. SOAP/HTTP)
   * @param implementor A service implementation object to which incoming requests will be
   * dispatched. The corresponding class MUST be annotated with all the necessary Web service
   * annotations.
   * @param features A list of WebServiceFeatures to configure on the endpoint.  Supported features
   * not in the <code>features </code> parameter will have their default values.
   * @return The newly created endpoint.
   * @since JAX-WS 2.2
   */
  public Endpoint createEndpoint(String bindingId, Object implementor,
      WebServiceFeature... features) {
    throw new UnsupportedOperationException(
        "JAX-WS 2.2 implementation must override this default behaviour.");
  }

  /**
   * Creates an endpoint object with the provided binding, implementation
   * class, invoker and web service features. Containers typically use
   * this to create Endpoint objects. <code>Provider</code>
   * implementations must override the default implementation.
   *
   * @param bindingId A URI specifying the desired binding (e.g. SOAP/HTTP). Can be null.
   * @param implementorClass A service implementation class that MUST be annotated with all the
   * necessary Web service annotations.
   * @param invoker that does the actual invocation on the service instance.
   * @param features A list of WebServiceFeatures to configure on the endpoint.  Supported features
   * not in the <code>features </code> parameter will have their default values.
   * @return The newly created endpoint.
   * @since JAX-WS 2.2
   */
  public Endpoint createEndpoint(String bindingId, Class<?> implementorClass,
      Invoker invoker, WebServiceFeature... features) {
    throw new UnsupportedOperationException(
        "JAX-WS 2.2 implementation must override this default behaviour.");
  }

}
